/**
 * API响应类型定义文件
 * 定义了前端与后端交互的接口类型
 * 与后端响应格式完全匹配
 */

// 导入通用类型
import { User, Role, Right, Region, Category } from './index';
// 重新导出这些类型
export type { User, Role, Right, Region, Category };
export type { News } from './news';

/**
 * 基础API响应类型
 * 与后端统一响应格式保持一致
 */
export interface ApiResponse<T = unknown> {
  code: number;       // 状态码：200-成功，400-参数错误，401-未授权，403-禁止访问，404-资源不存在，500-服务器错误
  msg?: string;       // 消息，后端使用msg而非message
  data?: T;           // 响应数据，可能为null/undefined
  error?: string;     // 错误信息，仅在出错时返回
  token?: string;     // 登录接口可能返回token
}

/**
 * 分页请求参数类型
 * 与后端分页规范保持一致
 */
export interface PaginationParams {
  page?: number;      // 页码，从1开始
  limit?: number;     // 每页条数，与后端一致使用limit
  sort?: string;      // 排序字段
  order?: 'asc' | 'desc'; // 排序方向
  [key: string]: unknown; // 其他可能的查询参数，使用unknown更安全
}

/**
 * 分页响应类型
 * 与后端分页响应格式一致
 */
export interface PaginationResult<T> {
  items: T[];         // 数据项数组，后端使用items
  total: number;      // 总记录数
  page: number;       // 当前页码
  limit: number;      // 每页条数
}

/**
 * MongoDB响应基础类型
 * 处理MongoDB特有的_id和__v字段
 */
export interface MongoDBResponse {
  _id: string;        // MongoDB ID
  __v?: number;       // MongoDB版本号
}

/**
 * 登录请求参数
 * 与后端登录接口匹配
 */
export interface LoginParams {
  username: string;   // 用户名
  password: string;   // 密码
  captcha?: string;   // 验证码（可选）
  remember?: boolean; // 记住登录（前端使用）
}

/**
 * 登录响应数据
 * 与后端登录成功响应匹配
 */
export interface LoginResult {
  id: string | number;       // 用户ID
  username: string;          // 用户名
  roleId: string | number;   // 角色ID
  role: {                    // 角色信息
    _id: string;             // 角色ID (MongoDB ObjectId)
    roleName: string;        // 角色名称
    rights: string[];        // 权限列表
    roleType: number;        // 角色类型
  };
  roleState: boolean;        // 账户状态
  region?: string;           // 所属区域
  token: string;             // JWT令牌
  default?: boolean;         // 是否默认用户
  permissions?: string[];    // 权限代码列表（可选）
}

/**
 * 权限验证请求参数
 * 用于权限检查接口
 */
export interface PermissionCheckParams {
  userId: string;            // 用户ID
  permissionKey: string;     // 权限键值
}

/**
 * 权限验证响应
 * 权限检查接口返回
 */
export interface PermissionCheckResult {
  hasPermission: boolean;    // 是否拥有权限
  user?: User;               // 用户信息（可选）
  role?: Role;               // 角色信息（可选）
}

/**
 * 修改密码请求参数
 */
export interface ChangePasswordParams {
  oldPassword: string;       // 旧密码
  newPassword: string;       // 新密码
  confirmPassword: string;   // 确认新密码
}

/**
 * 用户状态更新参数
 */
export interface UserStateParams {
  roleState: boolean;        // 用户状态：true-启用，false-禁用
}

/**
 * 用户创建参数
 */
export interface CreateUserParams {
  username: string;          // 用户名
  password: string;          // 密码
  roleId: string | number;   // 角色ID
  region: string;            // 区域
  roleState?: boolean;       // 状态
}

/**
 * 新闻查询参数
 */
export interface NewsQueryParams extends PaginationParams {
  auditState?: number;       // 审核状态
  publishState?: number;     // 发布状态
  author?: string;           // 作者
  category?: string;         // 分类
  region?: string;           // 区域
  keyword?: string;          // 关键词搜索
  startDate?: string;        // 开始日期
  endDate?: string;          // 结束日期
}

/**
 * 新闻审核参数
 */
export interface NewsAuditParams {
  auditState: number;        // 审核状态
  reason?: string;           // 审核意见（拒绝时必填）
}

/**
 * API错误类型扩展
 * 用于捕获和处理API请求错误
 */
export interface ApiError extends Error {
  response?: {
    status: number;          // HTTP状态码
    data?: ApiResponse;      // API响应数据
  };
  handled?: boolean;         // 是否已处理，避免重复处理
} 